home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Applications 1996 May / SGI IRIX 6.2 Applications 1996 May.iso / dist / impr_dev.idb / usr / include / spool.h.z / spool.h
C/C++ Source or Header  |  1996-05-06  |  14KB  |  357 lines
  1. /**************************************************************************
  2.  *                                      *
  3.  *           Copyright (c)    1991 Silicon Graphics, Inc.          *
  4.  *            All Rights Reserved                    *
  5.  *                                      *
  6.  *       THIS    IS UNPUBLISHED PROPRIETARY SOURCE CODE OF SGI          *
  7.  *                                      *
  8.  * The copyright notice above does not evidence any actual of intended      *
  9.  * publication of such source code, and is an unpublished work by Silicon *
  10.  * Graphics, Inc. This material contains CONFIDENTIAL INFORMATION that is *
  11.  * the property of Silicon Graphics, Inc. Any use, duplication or      *
  12.  * disclosure not specifically authorized by Silicon Graphics is strictly *
  13.  * prohibited.                                  *
  14.  *                                      *
  15.  * RESTRICTED RIGHTS LEGEND:                          *
  16.  *                                      *
  17.  * Use, duplication or disclosure by the Government is subject to      *
  18.  * restrictions as set forth in subdivision (c)(1)(ii) of the Rights in      *
  19.  * Technical Data and Computer Software clause at DFARS 52.227-7013,      *
  20.  * and/or in similar or successor clauses in the FAR, DOD or NASA FAR      *
  21.  * Supplement. Unpublished - rights reserved under the Copyright Laws of  *
  22.  * the United States. Contractor is SILICON GRAPHICS, INC., 2011 N.      *
  23.  * Shoreline Blvd., Mountain View, CA 94039-7311              *
  24.  **************************************************************************
  25.  *
  26.  * File: spool.h
  27.  *
  28.  * Description: Primary include file for libspool, the printer spooling
  29.  *    system API library. This file contains the declarations and
  30.  *    information required by application programs and should be
  31.  *    included by any program that references functions in libspool.
  32.  *
  33.  **************************************************************************/
  34.  
  35.  
  36. #ident "$Revision: 1.5 $"
  37.  
  38.  
  39. #ifndef    _SL_SPOOL_H
  40. #define    _SL_SPOOL_H
  41.  
  42.  
  43. #include <sys/types.h>
  44.  
  45.  
  46. /* Spooling systems */
  47.  
  48. #define SL_SPOOLER_NONE        0
  49. #define SL_SPOOLER_BSD        1
  50. #define SL_SPOOLER_SYSV        2
  51.  
  52. #define SL_POSSIBLE_SPOOLERS    ( SL_SPOOLER_BSD | SL_SPOOLER_SYSV )
  53.  
  54. #define SL_SPOOLER_PREF        SL_SPOOLER_SYSV
  55.  
  56. /* Spooler function and state info */
  57.  
  58. #define SL_PRINTING        0
  59. #define SL_QUEUEING        1
  60.  
  61. #define SL_DISABLED        0
  62. #define SL_ENABLED        1
  63.  
  64. /* Print queue types */
  65.  
  66. #define SL_QUEUE_LOCAL        1
  67. #define SL_QUEUE_REMOTE        2
  68. #define SL_QUEUE_MERGED        3
  69.  
  70. /* Printer specific options file save location tokens */
  71.  
  72. #define SL_SAVE_USER        0
  73. #define SL_SAVE_DEFAULT        1
  74.  
  75. /* Default netork timeout, in seconds */
  76.  
  77. #define SL_NET_TIMEOUT        20
  78.  
  79.  
  80. /* Error codes - indices into the SLerrlist array (except for SL_ERROR) */
  81.  
  82. #define SL_ERROR            -1
  83.  
  84. #define SL_NOERROR            0    /* No error detected */
  85. #define SL_ERR_FIND_SPOOLER        1    /* Could not shell out */
  86. #define SL_ERR_SPOOLER_NONE        2    /* SL_SPOOLER_NONE default */
  87. #define SL_ERR_NO_SPOOLERS        3    /* No spooling systems */
  88. #define SL_ERR_SPOOLER_UNKNOWN        4    /* Unknown spooling system */
  89. #define SL_ERR_NO_FILENAME        5    /* Invalid or missing filename*/
  90. #define SL_ERR_NUM_COPIES        6    /* Invalid num copies */
  91. #define SL_ERR_JOB_COPY            7    /* Invalid copy/link param */
  92. #define SL_ERR_NO_DEF_PRINTER        8    /* No default printer */
  93. #define SL_ERR_SPOOLER_ERROR        9    /* Spooling system error */
  94. #define SL_ERR_NO_JOBID            10    /* No job ID specified */
  95. #define SL_ERR_BAD_FUNCTION        11    /* Invalid spooling function */
  96. #define SL_ERR_BAD_STATE        12    /* Invalid spooling state */
  97. #define SL_ERR_NO_STATE            13    /* Can't get spooler state */
  98. #define SL_ERR_BAD_PRINTER_STRUCT    14    /* Invalid printer struct */
  99. #define SL_ERR_REMOTE            15    /* Can't get to remote host */
  100. #define SL_ERR_PRIVILEGE        16    /* Need root privilege */
  101. #define SL_ERR_MAIL            17    /* Invalid mail param */
  102. #define SL_ERR_BAD_FD            18    /* Invalid file descriptor */
  103. #define SL_ERR_BAD_BUF            19    /* Invalid print buffer */
  104. #define SL_ERR_BAD_PRINTER_NAME        20    /* Invalid printer name */
  105. #define SL_ERR_BAD_CLASS_MEMBER        21    /* Invalid class member */
  106. #define SL_ERR_NO_TEMP_FILE        22    /* Unable to create temp file*/
  107. #define SL_ERR_BAD_SOCKET        23    /* Problem with a socket */
  108. #define SL_ERR_NO_FAST_JOB        24    /* Fast job not supported */
  109. #define SL_ERR_NO_SYSV            25    /* System V spooler required */
  110. #define SL_ERR_SAVE_OPTIONS        26    /* Can't save options file */
  111.  
  112. /* Printer structure */
  113. /*    This structure describes a printer. The following notes
  114.     apply:
  115.  
  116.     1. On BSD systems it is assumed that the formal_name
  117.        is the last printer name to appear in the name list.
  118.  
  119.     2. On any spooling system, if the formal_name cannot
  120.        be determined it will be set to the type;
  121.  
  122.     3. On BSD systems the type field may be unavailble from
  123.        the /etc/printcap file and will be set to "Unknown".
  124.  
  125.     4. For networked printers the dev field will be set to
  126.        a NULL pointer.
  127.  
  128.     5. If the printer is local, the remote_host and remote_name
  129.        fields will be set to the NULL pointer.
  130.  
  131.     6. On BSD systems since one physical printer can have a
  132.        number of names, it is possible to have more than one
  133.        printer in the list marked as the default printer.
  134.  
  135.     7. On System V systems the is_class field is 1 if the printer
  136.        is actually a class. On BSD systems this field is always
  137.        false.
  138. */
  139.  
  140. typedef struct _slPrinterStruct {
  141.     char *local_name;            /* Printer name on the local machine */
  142.     char *formal_name;            /* Complete formal printer name */
  143.     char *type;                /* Type of printer (eg. Color) */
  144.     char *dev;                /* Port name (eg. /dev/plp) */
  145.                     /*     NULL pointer if networked */
  146.     unsigned int is_def: 1;        /* 1 == printer is the default */
  147.     unsigned int is_class: 1;        /* 1 == print is class (Sys V only) */
  148.     unsigned int is_networked: 1;    /* 1 == printer is physically */
  149.                     /*     located on a remote machine */
  150.     unsigned int _padding: 29;        /* Unused - for word alignment */
  151.     char *remote_host;            /* Name of remote machine */
  152.     char *remote_name;            /* Name of printer on remote machine */
  153.     char *network_type;                /* Type of network connection */
  154.                     /* to remote machine */
  155. } SLPrinterStruct;
  156.  
  157.  
  158. /* Printer settings structure */
  159. /*    The SGI printing environment provides a mechanism for
  160.     saving printer option settings on a per user per
  161.     printer basis. The PrintPanel tool allows a user to
  162.     set various job and printer related options and save
  163.     these settings. libspool provides the SLGetPrinterSettings
  164.     function to read the saved job and printer settings in
  165.     a spooler independent manner. This structure provides the
  166.     settings information. The settings information as contained
  167.     in this structure can be passed as parameters to the libspool
  168.     print job submittal functions such as SLSubmitJob. To read
  169.     spooling system specific settings refer to SLSysVGetPrinterSettings
  170.     and the SLSysVSettingsStruct below. The following notes apply:
  171.  
  172.     1. Printer and job settings are currently supported
  173.        only under System V spooling. Under BSD spooling
  174.        all fields will be set to default values.
  175. */
  176.  
  177. typedef struct _slSettingsStruct {
  178.     int copy;        /* 1 == copy to spooling area, 0 == link */
  179.     int mail;        /* 1 == send mail on job completion, 0 == no mail */
  180.     char *title;    /* Print job banner page title. If NULL the system */
  181.             /*    default banner title is to be used. */
  182.     char *options;    /* Spooling system specific options (e.g. -w and */
  183.             /*    -o under System V) */
  184. } SLSettingsStruct;
  185.  
  186.  
  187. /* System V spooler specific settings structure */
  188. /*    The SLGetSysVPrinterSettings function is similar to
  189.     SLGetPrinterSettings but provides the only spooler settings 
  190.     and provides them in a System V spooling system dependent
  191.     manner. See SLGetPrinterSettings above to obtain all settings
  192.     in a spooling system independent manner.
  193. */
  194.  
  195. typedef struct _slSysVSpoolerOptionsStruct {
  196.     int copy;        /* 1 == copy to spooling area, 0 == link */
  197.     int mail;        /* 1 == send mail on job completion, 0 == no mail */
  198.     int message;    /* 1 == send message on job completion, 0 == no msg */
  199.     int suppress_id;    /* 1 == suppress job ID message, 0 == show ID */
  200.     char *title;    /* Print job banner page title. If NULL the system */
  201.             /*    default banner title is to be used. */
  202. } SLSysVSpoolerOptionsStruct;
  203.  
  204.  
  205. /* Print job structure */
  206. /*    This structure describes a print job. A pointer to this
  207.     structure is returned after a job has been successfully
  208.     submitted for printing. The following notes apply:
  209.  
  210.     1. The job submittal functions maintain an internal
  211.        static structure for print jobs. The structure is
  212.        reused for each job submitted. It is the users
  213.        responsibility to make a copy of the job structure
  214.        if it is to be preserved.
  215.  
  216.     2. On BSD systems the job_id field will be NULL. To determine
  217.        the job ID one must examine the BSD queue and manually
  218.        determine the relevant job ID.
  219.  
  220.     3. On System V systems the job_id field will be NULL if
  221.        the '-s' flag is specified as an option.
  222.  
  223.     4. The username field contains the name of the user who
  224.        submitted the job. The name is derived based on the
  225.        real uid, not the euid. This is because the spooling 
  226.        system lists the owner of a job based on the real uid.
  227.        If the username cannot be determined, "Unknown" is entered
  228.        in this field.
  229. */
  230.  
  231. typedef struct _slPrintJob {
  232.     unsigned int spooler;        /* Spooling system that owns the job */
  233.                     /* eg. SL_SPOOLER_BSD */
  234.     char *printer;            /* Local name of the printer */
  235.     char *filename;            /* Name of file(s) to be printed */
  236.     char *username;            /* Job owner user name */
  237.     char *job_id;            /* Job ID, where available */
  238.     time_t time_stamp;            /* Time string from time(2). */
  239.                     /* See also ctime(3) */
  240. } SLPrintJob;
  241.  
  242.  
  243. /* Fast print job structure */
  244. /*    This stucture describes a fast print job; a pointer to this
  245.     structure is returned from a call to SLBeginFastJob, and it
  246.     contains information necessary for an application to execute
  247.     the fast print job.  The following notes apply:
  248.  
  249.     1. Only supported in System V spooler
  250. */
  251.  
  252. typedef struct _slFastPrintJob {
  253.     int sock;           /* A socket which has been marked as */
  254.             /* listening, which should be passed to */
  255.             /* accept, after which data can be sent */
  256.             /* to the printer driver */
  257.     SLPrintJob *job;    /* The return value of SLSubmitJobFile, which */
  258.             /* marks the job as it snakes its way through */
  259.             /* the spooling system */
  260. } SLFastPrintJob;
  261.  
  262.  
  263. /* Print queue entry */
  264. /*    This structure describes an entry on a printer queue.
  265.         The following notes apply:
  266.  
  267.     1. On BSD systems the time_stamp is 0.
  268.  
  269.     2. On BSD systems the is_local field is always 1.
  270. */
  271.  
  272. typedef struct _slQueueStruct {
  273.     char *job_id;            /* Job ID */
  274.     char *username;            /* Job owner's user name */
  275.     char *title;            /* Print job title, or name of */
  276.                     /* first file in request */
  277.     unsigned int size;            /* Size of the job in bytes */
  278.     unsigned int is_local: 1;        /* 1 == job is in the local */
  279.                     /*    queue (Sys V only) */
  280.     unsigned int _padding: 31;        /* Unused - for word alignment */
  281.     time_t time_stamp;            /* Submittal time (Sys V only) */
  282.                     /* From time(2). See also ctime(3) */
  283. } SLQueueStruct;
  284.  
  285.  
  286. /* Public global variables */
  287.  
  288. extern int    SLdebug;    /* Debug flag. Set non-zero for runtime info */
  289. extern long    SLnet_timeout;    /* Timeout (seconds) for network operations */
  290. extern int    SLerrno;    /* Error variable */
  291. extern char    *SLerrlist[];    /* Error strings */
  292. extern int    SLnerr;        /* Number of error strings in SLerrlist */
  293.  
  294.  
  295. /* Public function declarations */
  296.  
  297. #ifdef __cplusplus
  298. extern "C" {
  299. #endif
  300. extern void    SLPerror(const char *str);
  301. extern char*    SLErrorString(int err_code);
  302. extern int    SLGetSpooler(unsigned int *defaultp, unsigned int *availablep);
  303. extern int    SLSetSpooler(unsigned int spooler);
  304. extern int    SLGetPrinterList(SLPrinterStruct *printersp[],
  305.                 int *num_printersp);
  306. extern int    SLGetPrinterInfo(const char *printer,
  307.                 SLPrinterStruct **printer_infop);
  308. extern int    SLGetDefPrinterName(char **pnamep);
  309. extern int    SLGetPrinterSettings(const char *printer,
  310.                 SLSettingsStruct **settingsp);
  311. extern int    SLSysVGetSpoolerOptions(SLSysVSpoolerOptionsStruct
  312.                 **spooler_optsp);
  313. extern int    SLSysVGetPrinterOptions(const char *printer,
  314.                 char **printer_optsp);
  315. extern int    SLSysVSaveSpoolerOptions(SLSysVSpoolerOptionsStruct
  316.                 *spooler_opts);
  317. extern int    SLSysVSavePrinterOptions(const char *printer,
  318.                 char *printer_opts, int location);
  319. extern SLPrintJob*    SLSubmitJob(const char *filename, const char *printer,
  320.                 int num_copies, int copy, int mail,
  321.                 const char *title, const char *options);
  322. extern SLPrintJob*    SLSubmitJobFd(int file_desc, const char *printer,
  323.                 int num_copies, int copy, int mail,
  324.                 const char *title, const char *options);
  325. extern SLPrintJob*    SLSubmitJobBuf(const void *buffer, size_t amount,
  326.                 const char *printer, int num_copies,
  327.                 int copy, int mail, const char *title,
  328.                 const char *options);
  329. extern SLPrintJob*    SLSubmitJobSimple(const char *filename);
  330. extern int    SLCancelJob(const char *job_id, unsigned int spooler,
  331.                 const char *printer);
  332. extern int    SLGetSpoolerState(const char *printer, int function,
  333.                 int *statep);
  334. extern int    SLSetSpoolerState(const char *printer, int function,
  335.                 int state);
  336. extern int    SLGetQueue(const SLPrinterStruct *printer_info, int queue_type,
  337.                 SLQueueStruct *queuep[], int *num_queuep);
  338. extern int    SLGetSpoolerError(char **out_bufp[], int *noutp);
  339.  
  340. #ifdef _SL_FASTPATH
  341. /* DO NOT REFERENCE THESE FUNCTIONS */
  342. /* Code bracketed by _SL_FASTPATH is unsupported in this release. */
  343. extern SLFastPrintJob*    SLBeginFastJob(const char *printer, int ncopies,
  344.                        int mail, const char *title,
  345.                 const char *options);
  346. extern int    SLEndFastJob(SLFastPrintJob *fj);
  347. extern int    SLCancelFastJob(SLFastPrintJob *fj);
  348. extern int    SLSupportsFastJob(const char *printer);
  349. #endif /* _SL_FASTPATH */
  350.  
  351. #ifdef __cplusplus
  352. }
  353. #endif
  354.  
  355.  
  356. #endif    /* _SL_SPOOL_H */
  357.